

    \filetitle{dbplot}{Plot from database}{dbplot/dbplot}

	\paragraph{Syntax}

\begin{verbatim}
[FF,AA,PDb] = dbplot(D,List,Range,...)
[FF,AA,PDb] = dbplot(D,Range,List,...)
[FF,AA,PDb] = dbplot(D,List,...)
[FF,AA,PDb] = dbplot(D,Range,...)
[FF,AA,PDb] = dbplot(D,...)
\end{verbatim}

\paragraph{Input arguments}

\begin{itemize}
\item
  \texttt{D} {[} struct {]} - Database with input data.
\item
  \texttt{List} {[} cellstr \textbar{} rexp {]} - List of expressions
  (or labelled expressions) that will be evaluated and plotted in
  separate graphs; if not specified, all time series name found in the
  input database \texttt{D} will be plotted. Alternatively,
  \texttt{List} can be a regular expression (rexp object), which will be
  matched against all time series names in the input database.
\item
  \texttt{Range} {[} numeric {]} - Date range; if not specified, the
  function \href{dbase/dbrange}{\texttt{dbrange}} will be used to
  determined the plotted range (same for all graphs).
\end{itemize}

\paragraph{Output arguments}

\begin{itemize}
\item
  \texttt{FF} {[} numeric {]} - Handles to figures created by
  \texttt{qplot}.
\item
  \texttt{AA} {[} cell {]} - Handles to axes created by \texttt{qplot}.
\item
  \texttt{PDB} {[} struct {]} - Database with actually plotted series.
\end{itemize}

\paragraph{Options}

\begin{itemize}
\item
  \texttt{\textquotesingle{}addClick=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} {]} - Make axes expand
  in a new graphics figure upon mouse click.
\item
  \texttt{\textquotesingle{}captions=\textquotesingle{}} {[} cellstr
  \textbar{} @comment \textbar{} *empty* {]} - Strings that will be used
  for titles in the graphs that have no title in the q-file.
\item
  \texttt{\textquotesingle{}clear=\textquotesingle{}} {[} numeric
  \textbar{} \emph{empty} {]} - Serial numbers of graphs (axes objects)
  that will not be displayed.
\item
  \texttt{\textquotesingle{}dbSave=\textquotesingle{}} {[} cellstr
  \textbar{} \emph{empty} {]} - Options passed to \texttt{dbsave} when
  \texttt{\textquotesingle{}saveAs=\textquotesingle{}} is used.
\item
  \texttt{\textquotesingle{}deviationsFrom=\textquotesingle{}} {[}
  numeric \textbar{} \emph{empty} {]} - Each expression in \texttt{List}
  that starts with a \texttt{@} or \texttt{\#} (see Description) will be
  reported in deviations from this specified date.
\item
  \texttt{\textquotesingle{}deviationsTimes=\textquotesingle{}} {[}
  numeric \textbar{} \emph{empty} {]} - Used only if
  \texttt{\textquotesingle{}deviationsFrom=\textquotesingle{}} is
  non-empty; each expression in \texttt{List} that starts with a
  \texttt{@} or \texttt{\#} (see Description) will be reported in
  deviations multiplied by this number.
\item
  \texttt{\textquotesingle{}drawNow=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - Call Matlab
  \texttt{drawnow} function upon completion of all figures.
\item
  \texttt{\textquotesingle{}grid=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} {]} - Add grid lines to
  all graphs.
\item
  \texttt{\textquotesingle{}highlight=\textquotesingle{}} {[} numeric
  \textbar{} cell \textbar{} \emph{empty} {]} - Date range or ranges
  that will be highlighted.
\item
  \texttt{\textquotesingle{}interpreter=\textquotesingle{}} {[}
  \emph{\texttt{\textquotesingle{}latex\textquotesingle{}}} \textbar{}
  `none' {]} - Interpreter used in graph titles.
\item
  \texttt{\textquotesingle{}mark=\textquotesingle{}} {[} cellstr
  \textbar{} \emph{empty} {]} - Marks that will be added to each legend
  entry to distinguish individual columns of multivariated tseries
  objects plotted.
\item
  \texttt{\textquotesingle{}maxPerFigure=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{36}} {]} - Maximum number of graphs in one
  figure window; if the actual graph count exceeds
  \texttt{maxPerFigure}, the option `\texttt{subplot=}' is adjusted
  automatically, and new figure windows are opened as needed.
\item
  \texttt{\textquotesingle{}overflow=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - Open
  automatically a new figure window if the number of subplots exceeds
  the available total;
  \texttt{\textquotesingle{}overflow=\textquotesingle{}false} means an
  error will occur instead.
\item
  \texttt{\textquotesingle{}plotFunc=\textquotesingle{}} {[} @bar
  \textbar{} @hist \textbar{} *@plot* \textbar{} @plotcmp \textbar{}
  @plotpred \textbar{} @stem \textbar{} cell {]} - Plot function used to
  create the graphs; use a cell array, \texttt{\{plotFunc,...\}} to
  specify extra input arguments that will be passed into the plotting
  function.
\item
  \texttt{\textquotesingle{}prefix=\textquotesingle{}} {[} char
  \textbar{} \emph{\texttt{\textquotesingle{}P\%g\_\textquotesingle{}}}
  {]} - Prefix (a \texttt{sprintf} format string) that will be used to
  precede the name of each entry in the \texttt{PDb} database.
\item
  \texttt{\textquotesingle{}round=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{Inf}} {]} - Round the input data to this
  number of decimals before plotting.
\item
  \texttt{\textquotesingle{}saveAs=\textquotesingle{}} {[} char
  \textbar{} \emph{empty} {]} - File name under which the plotted data
  will be saved either in a CSV data file or a PS graphics file; you can
  use the \texttt{\textquotesingle{}dbsave=\textquotesingle{}} option to
  control the options used when saving CSV.
\item
  \texttt{\textquotesingle{}style=\textquotesingle{}} {[} struct
  \textbar{} \emph{empty} {]} - Style structure that will be applied to
  all figures and their children created by the \texttt{qplot} function.
\item
  \texttt{\textquotesingle{}subplot=\textquotesingle{}} {[}
  \emph{`auto'} \textbar{} numeric {]} - Default subplot division of
  figures, can be modified in the q-file.
\item
  \texttt{\textquotesingle{}sstate=\textquotesingle{}} {[} struct
  \textbar{} model \textbar{} \emph{empty} {]} - Database or model
  object from which the steady-state values referenced to in the
  quick-report file will be taken.
\item
  \texttt{\textquotesingle{}style=\textquotesingle{}} {[} struct
  \textbar{} \emph{empty} {]} - Style structure that will be applied to
  all created figures upon completion.
\item
  \texttt{\textquotesingle{}transform=\textquotesingle{}} {[}
  function\_handle \textbar{} \emph{empty} {]} - Function that will be
  used to trans
\item
  \texttt{\textquotesingle{}tight=\textquotesingle{}} {[} \texttt{true}
  \textbar{} \emph{\texttt{false}} {]} - Make the y-axis in each graph
  tight.
\item
  \texttt{\textquotesingle{}vLine=\textquotesingle{}} {[} numeric
  \textbar{} \emph{empty} {]} - Dates at which vertical lines will be
  plotted.
\item
  \texttt{\textquotesingle{}zeroLine=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - Add a horizontal
  zero line to graphs whose y-axis includes zero.
\end{itemize}

\paragraph{Description}

The function \texttt{dbplot} opens a new figure window (as many as
needed to accommodate all graphs given the option
\texttt{\textquotesingle{}subplot=\textquotesingle{}}), and creates a
graph for each entry in the cell array \texttt{List}.

\texttt{List} can contain either the names of database fields, or
expressions referring to database fields; these expressions will be then
evaluated in the input database context. You can also add labels (that
will be displayed as graph titles) enclosed in double quotes and
preceding the expressions. Alternatively, you can specify titles through
the option \texttt{\textquotesingle{}captions=\textquotesingle{}}. At
the beginning of the expression, you can use one of the following marks:

\begin{itemize}
\item
  \texttt{\^{}} (a hat symbol) means the function specified in the
  option \texttt{\textquotesingle{}transform=\textquotesingle{}} will
  not be applied to that expression;
\item
  \texttt{@} (an at symbol) in combination with the option
  \texttt{\textquotesingle{}deviationFrom=\textquotesingle{}} means that
  the deviations will reported in multiplicative form (i.e.~the actual
  value divided by the base period value).
\item
  \texttt{\#} (a hash symbol) in combination with the option
  \texttt{\textquotesingle{}deviationFrom=\textquotesingle{}} means that
  the deviations will reported in additive form (i.e.~the actual value
  minus the base period value).
\end{itemize}

\paragraph{Example}

The following command will plot the time series \texttt{x} and
\texttt{y} as deviations from \texttt{1} multiplied by \texttt{100} (see
the option \texttt{\textquotesingle{}transform=\textquotesingle{}}), and
the time series \texttt{z} as it is (because of the \texttt{\^{}} symbol
at the beginning). The first series will be labeled simply
\texttt{\textquotesingle{}x\textquotesingle{}}, while the last two
series will be labeled
\texttt{\textquotesingle{}Series\ y\textquotesingle{}} and
\texttt{\textquotesingle{}Series\ z\textquotesingle{}}, respectively.

\begin{verbatim}
dbplot(d,qq(2010,1):qq(2015,4), ...
   { 'x', '"Series y" y', '^"Series z"' }, ...
   'transform=',@(x) 100*(x-1));
\end{verbatim}

\paragraph{Example}

The following command will plot the time series \texttt{x} and
\texttt{y} as deviations from year 2000; \texttt{x} will be computed as
additive deviations (i.e.~the base period value will be subtracted from
its observations) whereas \texttt{y} will be computed as a
multiplicative deviations (i.e.~the observations will be divided by the
base period value). The last time series \texttt{z} will not be
transforme.d

\begin{verbatim}
dbplot(d,yy(2000):yy(2010), ...
   { '# x', '@ y', 'z' }, ...
   'deviationsFrom=',yy(2000));
\end{verbatim}

\paragraph{Example}

The following command will plot all time series found in the database
that start with \texttt{\textquotesingle{}a\textquotesingle{}}.

\begin{verbatim}
dbplot(d,rexp('^a.*'));
\end{verbatim}

\paragraph{Example}

Create an example database with the following fields: \texttt{c},
\texttt{ctrend}, \texttt{y}, \texttt{ytrend}, \texttt{k},
\texttt{ktrend} (the exact way these series are created is, of course,
irrelevant):

\begin{verbatim}
range = qq(2000,1):qq(2004,4);
s = struct();
s.c = 1+cumsum( tseries(range,@rand)/10 );
s.ctrend = hpf(s.c);
s.y = 1+cumsum( tseries(range,@rand)/10 );
s.ytrend = hpf(s.y);
s.k = 1+ cumsum( tseries(range,@rand)/10 );
s.ktrend = hpf(s.k);
disp(s);
\end{verbatim}

Plot the individual series against their respective trends, each in its
own graph:

\begin{verbatim}
dbplot(s,range, ...
    { '[c,ctrend]', '[y,ytrend]', '[k,ktrend]' } );
\end{verbatim}

To automate this task, create the list of expressions to be plotted
using the standard Matlab function \texttt{strcat}:

\begin{verbatim}
list = {'c','y','k'};
plotList = strcat( '[' , list , ',' , list , 'trend]' );
disp(plotList);
dbplot(s,range,plotList);
\end{verbatim}

In the case of some complex transformation(s), e.g.

\begin{verbatim}
dbplot(s,range, { ...
    '100*log([c,ctrend])',  ...
    '100*log([y,ytrend])', ...
    '100*log([k,ktrend])' } );
\end{verbatim}

use the option \texttt{\textquotesingle{}transform=\textquotesingle{}}
to apply the specified function to all series before they get plotted:

\begin{verbatim}
dbplot(s,range, ...
    { '[c,ctrend]', '[y,ytrend]', '[k,ktrend]' }, ...
    'transform=',@(x) 100*log(x) );
\end{verbatim}

If some graphs need to be excluded from
\texttt{\textquotesingle{}transform=\textquotesingle{}}, use a hat
\texttt{\^{}} at the beginning of the expression:

\begin{verbatim}
dbplot(s,range, ...
    { '[c,ctrend]', '[y,ytrend]', '^[k,ktrend]' }, ...
    'transform=',@(x) 100*log(x) );
\end{verbatim}

Include titles for the individual graphs in double quotes at the
beginning of each expression:

\begin{verbatim}
dbplot(s,range, { ...
    '"Consumption" [c,ctrend]', ...
    '"Output" [y,ytrend]', ...
    '"Capital" [k,ktrend]' } );
\end{verbatim}

or alternatively use the option
\texttt{\textquotesingle{}captions=\textquotesingle{}} to do the same
thing:

\begin{verbatim}
dbplot(s,range, ...
    { '[c,ctrend]', '[y,ytrend]', '[k,ktrend]' }, ....
    'captions=',{'Consumption','Output','Capital'} );
\end{verbatim}


